home *** CD-ROM | disk | FTP | other *** search
/ GameStar 2004 April / Gamestar_61_2004-04_dvdb.iso / DVDStar / Editace / hltp.exe / {app} / Applications / RESGen / manual.txt < prev    next >
Text File  |  2003-09-07  |  9KB  |  228 lines
  1. RESGen v2.0 manual
  2.  
  3. INDEX
  4. 1. Copyright and warranty
  5. 2. About RESGen
  6. 3. Command line parameters
  7. 4. Changes between v1 and v2
  8. 5. Using resource verification
  9. 6. Credits
  10. 7. Changelog
  11.  
  12.  
  13. 1. Copyright and warranty
  14.     RESGen. A tool to create .res files for Half-Life.
  15.     Copyright (C) 2000-2003 Jeroen Bogers
  16.     
  17.     RESGen is free software; you can redistribute it and/or modify
  18.     it under the terms of the GNU General Public License as published by
  19.     the Free Software Foundation; either version 2 of the License, or
  20.     (at your option) any later version.
  21.     
  22.     RESGen is distributed in the hope that it will be useful,
  23.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  24.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  25.     GNU General Public License for more details.
  26.     
  27.     You should have received a copy of the GNU General Public License
  28.     along with RESGen; if not, write to the Free Software
  29.     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  30.  
  31.     
  32. 2. About RESGen
  33.     RESGen is a tool to create res (resource) files for Half-Life.
  34.     If a Half-Life map has a corresponding res file, Half-Life is able to
  35.     send all resources the resources the map uses to the clients, if they
  36.     don't have them. This helps a great deal when running a server with
  37.     custom maps, instead of the defaults. Most players do not have these
  38.     custom maps and the resources that should go with them. The res file
  39.     enables them to download the map via Half-Life and start playing right
  40.     away.
  41.     The problem with res files, however, is that it can take hours to create
  42.     one if the resources used by a map are not known. RESGen can shorten this
  43.     time to mere seconds. It reads the maps BSP file and searches it for
  44.     used resources. The results of this search are then used to create the
  45.     res file.
  46.  
  47.  
  48. 3. Command line parameters
  49.     -h help
  50.         Displays the help screen.
  51.     
  52.     -c
  53.         Displays the RESGen credits.
  54.     
  55.     -w
  56.         Displays the warranty for RESGen.
  57.     
  58.     -v
  59.         Makes RESGen only give minimal output.
  60.         It's recommended you use this if you want to create res files as fast
  61.         as possible. RESGen will still report any error.
  62.     
  63.     -s
  64.         RESGen will not display it's status line. This might considerably speed
  65.         up res file generation, especially on smaller maps.
  66.     
  67.     -i
  68.         RESGen will only report the base folder it's searching, but not the
  69.         subfolders. Useful with -r option.
  70.     
  71.     -j
  72.         Resources found while building the resource list will not be displayed.
  73.         Useful with -e option.
  74.     
  75.     -d [folder]
  76.         [folder] will be searched for bsp files. A trailing (back)slash is
  77.         optional.
  78.     
  79.     -r [folder]
  80.         [folder] and it's subfolders will be searched for bsp files. A trailing
  81.         (back)slash is optional.
  82.     
  83.     -f [map]
  84.         A res file will be generated for [map]. The .bsp file extension is
  85.         optional.
  86.     
  87.     -x [map]
  88.         Exclude this map from res file generation. Only works on maps found
  89.         with -d or -r options. The .bsp file extension is optional.
  90.     
  91.     -o
  92.         If a res file already exists it will be overwritten.
  93.     
  94.     -a [rfafile]
  95.         The contents of the rfa file will be added to the end of the res file.
  96.         This is useful when adding custom resources, like the StatsMe
  97.         sound pack. The .rfa file extension is optional.
  98.     
  99.     -l
  100.         Turns off converting all res file entries to lowercase. RESGen converts
  101.         all res file entries to lowercase since this is the    default for
  102.         Half-Life files. It has to do this because a lot of resource files in
  103.         maps don't have the proper case that matches the actual    resources.
  104.         Only use this option if you know what you are doing.
  105.     
  106.     -e [modpath]
  107.         Makes RESGen verify that all resources in the res file actually exist.
  108.         Resources that can't be found will be excluded from the res file.
  109.         RESGen expects modpath to point to a valid mod directory structure.
  110.         If the modpath isn't the valve folder, RESGen will try to find the
  111.         valve folder too, so a complete resource list can be established.
  112.     
  113.     -p
  114.         Prevents RESGen from using the contents of any pakfile for resource
  115.         verification. Thus, any resource that is available, but in a pakfile
  116.         is excluded from the res file. This option is only useful when the
  117.         -e option is also used. Please note that if a map comes with it's own
  118.         pakfile, using this option will generate a res file that is
  119.         incomplete.
  120.     
  121.     -k
  122.         Windows only. RESGen will not wait for the user to press a key to exit.
  123.     
  124.     -t
  125.         Linux only. RESGen will ignore symbolic links when searching folders
  126.         for .bsp files. Please note that this does NOT affect resource
  127.         searching. Useful with -d or -r options.
  128.     
  129.     
  130.     Example:
  131.         resgen -ok -r C:\sierra\half-life\tfc -e C:\sierra\half-life\tfc -a shadowlord.rfa
  132.     
  133.     This will make RESGen generate res files for all maps that are in the tfc
  134.     folder. It will verify it's resources from the tfc folder and the valve
  135.     folder (C:\sierra\half-life\valve). Any existing res file will be
  136.     overwritten. The contents of shadowlord.rfa will be added to all res files.
  137.     When RESGen is finished it will exit immediately, not waiting for a
  138.     keypress.
  139.  
  140.  
  141. 4. Changes between v1 and v2
  142.     From the outside RESGen 1 and 2 look similar. On the inside a lot of
  143.     changes have been made. First of all, major parts have been rewritten,
  144.     and other parts have had a major upgrade. The biggest change is that the
  145.     RESGen core is fully C++ now, instead of a bit C++ in a C program.
  146.     Because of this I have DROPPED the scripting return values. It's very
  147.     easy to use the RESGen source in your own programs now.
  148.  
  149.     The RESGen parser should be a bit faster now. It's speed mainly depends
  150.     on the speed of your hard disk and your output window. That last limitation
  151.     can be overcome by using the -v option (minimal output).
  152.  
  153.     The last major change is the -e option. It enables you to have RESGen
  154.     automatically verify if you server actually has the resources the map
  155.     claims to need. This especially applies to missing wad files. See
  156.     chapter 4 for more information on how to use the -e option.
  157.  
  158.     Additionally, RESGen now tries to locate the maps information txt and
  159.     overview pictures. Please note that RESGen can only find these if they
  160.     are stored in the same folder layout as they would be on the server
  161.     (mapname.txt, ../overviews/mapname.txt and ../overviews/mapname.bmp).
  162.  
  163.  
  164. 5. Using resource verification
  165.     The -e option, can be quite powerful. It can be used several ways.
  166.     Here I try to describe a few of the more common ways, although there
  167.     are many more.
  168.     NOTE: There is a subtle difference between Win32 and the Linux when
  169.     checking if a resource is available or not. On Win32 RESGen does not
  170.     care about case when comparing the found files to the res entry. On
  171.     Linux it does care about it and reject resources when the case
  172.     doesn't match. In 99% of the cases this doesn't matter. However,
  173.     because of this difference it it's recommended to run RESGen on the
  174.     target platform whenever possible.
  175.     
  176.     Method 1, the simple way:
  177.     This method is most commonly used by server admins that want to add
  178.     res files to their servers. Run RESGen on the mod folder you want to
  179.     make res files for. Point the -e option to this folder too. This
  180.     will generate good res files, which contain all found resources.
  181.     You should not use the -p option unless you are certain that you
  182.     have no maps with their own pakfile.
  183.     Example: resgen -r half-life\cstrike -e half-life\cstrike
  184.     
  185.     Method 2, the mapper way:
  186.     You run resgen on the map, and point the -e option to the folder with
  187.     the resources (these can be the same). Please note that the resource
  188.     folder must match the folder layout of a normal folder.
  189.     Using -p is possible if you aren't using a pakfile for your map.
  190.     Also, note that resgen will look for the map info txt and overviews 
  191.     relative to the map itself, not the folder specified with -e
  192.     Example: resgen -f mymap.bsp -e mapping\resourcetank
  193.  
  194.  
  195. 6. Credits
  196.     This program was made by Jeroen "ShadowLord" Bogers.
  197.     E-mail: resgen@hltools.com
  198.     URL: http://resgen.hltools.com
  199.  
  200.     Special thanks to:
  201.         "HoundDawg" and UnitedAdmins for hosting this program.
  202.         "luvless" for having the great idea to create this app.
  203.         Valve for creating Half-Life!
  204.         Everyone who uses RESGen.
  205.  
  206.  
  207. 7. Changelog
  208.     Version 2.0 BETA 2
  209.      - Bugfix: The parsing enigne crashed when the BSP entity data wasn't in
  210.        Linux format. It now can work with data in Windows format too. If the
  211.        BSP is in any other format, the parser will generate an error, instead
  212.        of crashing.
  213.      - Bugfix: If there were no WAD files specified for a map, the parser gave
  214.        an error message for the map and stopped parsing it. It now correctly
  215.        handles this and can continue parsing the rest of the BSP.
  216.      - Fix: Entity data corruption errors now give a bit more information about
  217.        what is wrong with the data.
  218.      - Bugfix: While running RESGen I discovered that the memory use increased
  219.        with every parsed map. After running a memmory leak detector and
  220.        reviewing the code, I discovered that I forgot to close the BSP files
  221.        after reading them (doh). They are now properly closed and there is no
  222.        more memory leaking. (That I know of anyways :)
  223.  
  224.     Version 2.0 BETA 1
  225.      - New: Initial release. Total rework of the parsing engine. Also much more
  226.        object oriented.
  227.  
  228.